Skip to main content

Ansible Module – Infra API

Overview​

The AnsibleService is part of the infra API layer responsible for executing Ansible playbooks programmatically within the application runtime. It integrates with the system’s logging and task tracking architecture to ensure infrastructure tasks are automated and auditable.

Purpose​

This service provides controlled execution of Ansible playbooks, allowing:

  • Declarative infrastructure provisioning
  • Automated configuration management
  • Task-tracked logging to a central database
  • Dynamic execution with inventory and variable injection

Architecture​

Key Components:​

  • AnsibleModule (NestJS Module) Exposes the AnsibleService for injection into other parts of the application.

  • AnsibleService (NestJS Injectable Service) Contains all the logic for executing Ansible playbooks via Node.js's child_process.spawn() and for logging the outputs to the AgentTaskOutput table.

Functionality​

1. Playbook Execution (Basic)​

Executes a given Ansible playbook with a list of variables defined in JSON/YAML files. No inventory file is used in this mode. Useful for isolated operations that don’t require target host listings.

2. Playbook Execution With Inventory​

Supports running playbooks against dynamic or preconfigured hosts using Ansible inventory files. Also supports passing extra vars.

This mode is most suitable for environment-specific provisioning (e.g., provisioning VMs on staging, dev, or prod).

3. Integrated Logging to DB​

Each line of stdout and stderr from the Ansible playbook execution is streamed and saved as a log entry in the AgentTaskOutput table, allowing traceable and auditable infra execution tied to an AgentTask.

Log format:

[INFO] or [ERROR] <output>

Database Integration​

Logs are written to the AgentTaskOutput model, which includes:

  • refType: Hardcoded as 'AgentTasks' to track which kind of reference it is
  • refId: The specific AgentTask.id that triggered the execution
  • output: The actual log data (text)

Error Handling​

  • All execution errors are logged both to the console (Logger) and persisted to the database.
  • Non-zero exit codes from the Ansible process cause promise rejections with full context of stdout and stderr.

File Management​

Includes a utility to delete temporary variable files (e.g., generated secrets or runtime config), helping maintain a clean execution environment.

Use Cases​

  • Provisioning a new VM or container using pre-written playbooks
  • Applying a security patch or configuration update on all hosts
  • Reconfiguring environments based on user or task inputs
  • Automating deployment of infrastructure as part of a CI/CD pipeline

Dependencies​

  • NestJS: Module + Dependency Injection
  • Prisma ORM: Used via DBService to write to the AgentTaskOutput table
  • Node.js child_process: To spawn Ansible CLI processes
  • Node.js fs/promises: For async file operations like cleanup

Extensibility Ideas​

  • Add support for dry runs (--check)
  • Enable inline vars (in addition to file-based vars)
  • Capture task execution metadata (duration, host info, result summary)
  • WebSocket support for real-time log streaming to frontend